Objects
Operation Type
OperationType
An enum representing different types of transactions.
Possible Values:
sale
refund
refundReversal
saleReversal
saleAndTokenizeCard
tokenizeCard
printReceipt
update
cardPan
pingDevice
stopCurrentTransaction
Operation Types Description
OperationTypesDescription
Parameter | Notes |
---|---|
sale String | A sale initiates a payment operation to the card reader |
refund String | A refund operation moves funds from the merchant account to the cardholder´s credit card. For Interac (Canadian Debit Network), refunds can only be processed until Interac closes the batch of transactions at night |
refundReversal String | A refund reversal, also called refund VOID allows the merchant to reverse a previous refund operation. This operation reverts (if possible) a specific refund identified with a transaction id |
saleReversal String | A sale reversal, also called sale VOID allows the user to reverse a previous sale operation. This operation reverts (if possible) a specific sale identified with a transaction id |
saleAndTokenizeCard String | A sale operation which also returns a card token (not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice) |
tokenizeCard String | Returns a card token (not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice) |
printReceipt String | This method sends the merchant or customer receipt to the terminal for printing. The format of the HTML data, stored in the URL or passed in the value of the receipt key, must follow this format: HTML Print Format |
update String | The update operation checks for new software or configuration updates and initiates a download if required. |
cardPan String | A cardPan request will return the full PAN of the card being swiped, dipped or tapped. Only the PANs of whitelisted card ranges will be returned by the Handpoint systems. This operation is mostly used to be able to process funds or points from loyalty cards. |
pingDevice String | This operation will ping the terminal to confirm if it is online. |
stopCurrentTransaction String | Operation used to stop the current transaction. The transaction can only be stopped at specific stages of a payment processing, for example a transaction can not be stopped when the card is being read but can be stopped when waiting for the cardholder to initially insert a card. |
Financial Status
Financial Status
:
UNDEFINED
AUTHORISED
DECLINED
PROCESSED
FAILED
CANCELLED
PARTIAL_APPROVAL
Description of the different financial statuses:
Parameter | Notes |
---|---|
UNDEFINED | Any Financial Status other than the below mentioned financial statuses will be UNDEFINED . UNDEFINED means that the API couldn't get a response from the Gateway. An automatic cancellation service will try to cancel the transaction in case it was approved. |
AUTHORISED | The transaction (Sale, Refund,...) has been authorised. Consider this value as "successful". |
DECLINED | The transaction has been declined by the acquirer or issuer. |
PROCESSED | The printReceipt operation was successful. |
FAILED | Status generated due to a network error, a card which can not be read etc. As a general rule, errors are mapped to FAILED . |
CANCELLED | The transaction has been cancelled. For example if the stopCurrentTransaction operation has been used or the cancel button on the terminal has been pressed. |
PARTIAL_APPROVAL | A partial approval is the ability to partially authorize a transaction if the cardholder does not have the funds to cover the entire cost on their card. The merchant can obtain the remainder of the purchase amount in another form of payment. PARTIAL_APPROVAL is only applicable to the United States market. |
Transaction Result Object
TransactionResult
An object holding information about the result of a transaction.
An object holding information about the result of a transaction.
Property | Description |
---|---|
aid String | Application Identifier of the card (EMV tag 9F06) |
arc String | EMV Authorisation Response Code (EMV tag 8A) |
authorisationCode String | Acquirer response code |
balance Balance | Balance available on the card |
budgetNumber String | Used to split payments over a period of months |
cardEntryType CardEntryType | Method used by the terminal to read the card |
cardLanguagePreference String | Preferred language of the card (EMV tag 5F2D) |
cardSchemeName CardSchemeName | The brand of the card |
cardToken String | Token representing the PAN of the card |
chipTransactionReport String | Full report of the card EMV parameters |
currency Currency | The currency used for the transaction |
customerReceipt String | A URL containing the customer receipt in HTML format |
customerReference String | If a customerReference was provided as an optional parameter in the transaction request it is echoed unaltered in this field |
deviceStatus DeviceStatus | Status of the device |
dueAmount BigString | In case of a partial approval for the transaction, this field contains the amount which remains to be paid |
efttimestamp BigString | Time of the transaction |
efttransactionID String | Handpoint unique identifier for a transaction, this id is the one to be used for a transaction to be reversed. |
errorMessage String | Detailed reason for the transaction error |
expiryDateMMYY String | Expiry date of the card used for the operation |
finStatus FinancialStatus | The financial status contains the outcome of the transaction. For example "AUTHORISED" or "DECLINED" |
iad String | Issuer Application Data (EMV tag 9F10) |
issuerResponseCode String | Response code from the card issuer |
maskedCardNumber String | Masked card number of the card used for the operation |
merchantAddress String | Merchant Address |
merchantName String | Merchant Name |
merchantReceipt String | A URL containing the customer receipt in HTML format |
mid String | Merchant Identifier |
originalEFTTransactionID String | In case the transaction type is a reversal, this field will contain the identifier of the original transaction being reversed |
paymentScenario PaymentScenario | Indicates the card entry mode |
recoveredTransaction boolean | This flag is set to true if the transaction result is sent through the transaction recovery logic explained in the Recovey Section, false otherwise |
requestedAmount BigInteger | The requested amount is the transaction amount sent to the terminal |
rrn String | Retrieval Reference Number, unique number assigned by the acquirer |
signatureUrl String | If a digital signature is required, this is the URL containing the image of the captured signature |
statusMessage String | The status of the transaction, for example "Waiting for pin" |
tenderType TenderType | Transaction tender type (credit / debit) |
tid String | MerchTerminalant Identifier |
tipAmount BigInteger | Tip amount, if any, in the minor unit of currency (f.ex. 1000 is 10.00 GBP) |
tipPercentage double | If tipping is enabled, this field will return the tip percentage added on top of the base amount |
totalAmount BigInteger | The total amount is the amount the card was charged for. It is possible that the total amount is not the same as the requested amount since an additional fee can be added, with the customer's approval, via the tipping functionality |
transactionID String | The transaction id is a terminal internal counter incremented for each transaction |
tsi String | Transaction Status Information (EMV tag 9B) |
tvr String | Transaction Verification Results (EMV tag 95) |
type TransactionType | The type of transaction initiated, for example "SALE" |
unMaskedPan String | Unmasked PAN, only received if the card is a non-payment card (loyalty) |
verificationMethod VerificationMethod | cardholder verification method, for example "PIN" |
multiLanguageStatusMessages Map | Containing the status message in a human readable format for all the supported locales. |
multiLanguageErrorMessages Map | Containing the error message in a human readable format for all the supported locales. |
cardHolderName String | Name of the cardholder |
Code example
{
"aid": "A0000000041010",
"arc": "0000",
"authorisationCode": "123456",
"balance": null,
"budgetNumber": "",
"cardEntryType": "UNDEFINED",
"cardLanguagePreference": "",
"cardSchemeName": "MasterCard",
"cardToken": "",
"chipTransactionReport": "",
"currency": "USD",
"customerReceipt": "https://s3.[...]/customerReceipt.html",
"customerReference": "",
"deviceStatus": {
"applicationName": "ClientApp",
"applicationVersion": "20.1.0",
"batteryCharging": "Not Charging",
"batteryStatus": "100",
"batterymV": "4126",
"bluetoothName": "PAXA920",
"externalPower": "USB",
"serialNumber": "0821032398",
"statusMessage": "Approved or completed successfully"
},
"dueAmount": 0,
"errorMessage": "",
"expiryDateMMYY": "0422",
"finStatus": "AUTHORISED",
"iad": "0210A000002A0000000000000000000000FF",
"issuerResponseCode": "00",
"maskedCardNumber": "************1456",
"merchantAddress": "Plaza Soledad Torres Acosta 1 28013 Madrid",
"merchantName": "Hago la cama",
"merchantReceipt": "https://s3.[...]/merchantReceipt.html",
"mid": "",
"originalEFTTransactionID": "",
"paymentScenario": "CHIPCONTACTLESS",
"rrn": "",
"signatureUrl": "",
"statusMessage": "Approved or completed successfully",
"tenderType": "CREDIT",
"tid": "ACQUIRER_TID",
"tipAmount": 0,
"totalAmount": 100,
"transactionID": "01236fc0-8192-11eb-9aca-ad4b0e95f241",
"tsi": "0000",
"tvr": "0400008001",
"type": "SALE",
"unMaskedPan": "",
"verificationMethod": "UNDEFINED",
"efttimestamp": 1615374961000,
"efttransactionID": "01236fc0-8192-11eb-9aca-ad4b0e95f241",
"requestedAmount": 100,
"tipPercentage": 0,
"recoveredTransaction": false,
"cardHolderName": "Mr/Mrs card holder full name"
}
Transaction Request Object
TransactionRequest
An object to store the information about the payment terminal in use
Properties
Property | Description |
---|---|
operation Required OperationTypesDescription | The type of transaction to be performed. |
serial_number Required String | Device serial number. |
terminal_type Required String | Device type. |
callbackUrl String | if used, url the terminal will use to send the Transaction Result. All 2XXs http response codes from the callbackUrl are valid to notify the terminal of a successful delivery of the result. If the callbackUrl is not present, the device will send back the transaction result to Handpoint's REST-API and results can be retrieved using the Transaction Result Retrieval endpoint |
token Required String | Token used to authenticate the terminal and transaction when serving the Transaction Result through the callbackUrl . The token will be injected in the Request Header with key value 'AUTH-TOKEN'. REQUIRED when the callbackUrl is present. |
customerReference String | Transaction identifier provided by the integrator. The customerReference sent in TransactionRequests objects is echoed in the TransactionResults |
amount Required String | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 EUR). REQUIRED for operations: sale, refund, refundReversal, saleReversal and saleAndTokenizeCard. |
currency Required Currency | The currency of the transaction. REQUIRED for operations: sale, refund, refundReversal, saleReversal and saleAndTokenizeCard. |
originalTransactionId Required String | The transaction id of the original transaction to reverse. REQUIRED for operations: refundReversal, saleReversal and LINKED refunds. |
receipt Required String | HTML receipt, following the format defined in Html Print Format, or url to locate the receipt, it can be found in the response of a Transaction Request, in the fields merchantReceipt or customerReceipt. REQUIRED for operations: printReceipt. |
tipConfiguration TipConfiguration | Configuration to enable tipping. At the time of sale, a tip menu will be shown to the cardholder with the predefined configuration. The tip configuration is optional and can only be used with the sale and saleAndTokenize operations. |
bypassOptions ByPassOptions | Configuration to enable the possibility of bypassing signature or pin. The bypass configuration is optional and can only be used with the sale, saleAndTokenize and refund operations |
merchantAuth MerchantAuth | Object used to store merchant authentication. The merchantAuth is optional and can only be used with the sale, saleAndTokenize and refund operations. For reversals, the credentials passed for the original sale will be automatically looked up by Handpoint and used to process the reversal. This object allows a transaction to be funded to a specific merchant account other than the default one. It is useful if a terminal is shared between multiple merchants, for example at an Hair Salon or a Doctor's office. |
Code example
// Result will be served to result.com
{
"operation": "sale",
"amount": "10000",
"currency": "EUR",
"terminal_type": "PAXA920",
"serial_number": "1547854757",
"customerReference": "storeSale12548",
"callbackUrl": "https://result.com",
"token": "123456789",
"tipConfiguration": {
"baseAmount": "2000",
"tipPercentages": [5,10,15,20,25],
"enterAmountEnabled": true,
"skipEnabled": false,
"footer": "Thank you!!! ;)"
},
"bypassOptions": {
"signatureBypass": true,
"pinBypass": true
},
"merchantAuth": [{
"acquirer": "ACQ_DUMMY",
"mid": "1111",
"tid": "2222",
"mcc": "3333",
"externalId": "4444"
}]
}
// Result will be served back to Handpoint's REST-API
{
"operation": "sale",
"amount": "10000",
"currency": "EUR",
"terminal_type": "PAXA920",
"serial_number": "1547854757",
"customerReference": "storeSale12548",
"tipConfiguration": {
"baseAmount": "2000",
"tipPercentages": [5,10,15,20,25],
"enterAmountEnabled": true,
"skipEnabled": false,
"footer": "Thank you!!! ;)"
},
"bypassOptions": {
"signatureBypass": true,
"pinBypass": true
},
"merchantAuth": [{
"acquirer": "ACQ_DUMMY",
"mid": "1111",
"tid": "2222",
"mcc": "3333",
"externalId": "4444"
}]
}
Bypass Options
BypassOptions
Configuration to enable/disable signature or pin bypass.
Property | Description |
---|---|
pinBypass Boolean | Enables/disables pin bypass. Bypasses PIN entry when the shopper says they don't know the PIN for the card and the merchant either knows they are the legitimate cardholder or want to give them the benefit of the doubt. |
signatureBypass Boolean | Enables/disables signature bypass. Whether the terminal prompts for a signature, depends on how you configure this parameter. The major card schemes (American Express, Diners, Discover, JCB, Mastercard, Visa, UnionPay) no longer require a signature; they regard it as optional for card-present transactions. This means you can speed up your checkout by skipping the signature prompt. But if your business requires it, you can still let the terminal prompt for a signature. The shopper then provides their signature on the touch screen of the terminal or on the printed transaction receipt. This depends on how you configure this setting. It is your responsibility to verify the signature of the shopper with the signature on the card or another form of identification. |
Code example
{
"bypassOptions": {
"signatureBypass": true,
"pinBypass": true
}
}
Merchant Auth
MerchantAuth
Object used to store merchant authentication. This object is optional, it allows a transaction to be funded to a specific merchant account other than the default one. It is useful if a terminal is shared between multiple merchants, for example at an Hair Salon or a Doctor's office.
Property | Description |
---|---|
Credential Credential[] | Array of credentials |
Code example
{
"merchantAuth": [{
"acquirer": "ACQ_DUMMY",
"mid": "1111",
"tid": "2222",
"mcc": "3333",
"externalId": "4444"
}]
}
Acquirer
Acquirer
An enum representing the supported acquirers for merchant authentication.
Possible values
AMEX
BORGUN
EVO
OMNIPAY
POSTBRIDGE
INTERAC
TSYS
VANTIV
SANDBOX
Device
Device
An object to store the information about the payment terminal you are working with. ALL values are REQUIRED
Properties
Property | Description |
---|---|
merchant_id_alpha Required String | Merchant unique identifier to which the device is associated |
serial_number Required String | Device serial number |
ssk Required String | Merchant shared secret key, unique id for the merchant |
terminal_type Required String | Device type |
Code example
{
"merchant_id_alpha": "Test_Merchant",
"serial_number": "614004878",
"ssk": "74817EA5C63437ADE7AA3A5401",
"terminal_type": "PAXA920"
}
Currency
Currency
An enum of most currencies in the world.
Contains the ISO name, ISO number and the name of the currency. Additionally contains information about how many decimals the currency uses.
Possible values
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
AWG
AZN
BAM
BBD
BDT
BGN
BHD
BIF
BMD
BND
BOB
BOV
BRL
BSD
BTN
BWP
BYR
BZD
CAD
CDF
CHF
CLP
CNY
COP
COU
CRC
CUC
CUP
CVE
CZK
DJF
DKK
DOP
DZD
EEK
EGP
ERN
ETB
EUR
FJD
FKP
GBP
GEL
GHS
GIP
GMD
GNF
GTQ
GYD
HKD
HNL
HRK
HTG
HUF
IDR
ILS
INR
IQD
IRR
ISK
JMD
JOD
JPY
KES
KGS
KHR
KMF
KPW
KRW
KWD
KYD
KZT
LAK
LBP
LKR
LRD
LSL
LTL
LVL
LYD
MAD
MDL
MKD
MMK
MNT
MOP
MUR
MVR
MWK
MXN
MXV
MYR
MZN
NAD
NGN
NIO
NOK
NPR
NZD
OMR
PAB
PEN
PGK
PHP
PKR
PLN
PYG
QAR
RON
RSD
RUB
RWF
SAR
SBD
SCR
SDG
SEK
SGD
SHP
SLL
SOS
SRD
STD
SYP
SZL
THB
TJS
TMT
TND
TOP
TRY
TTD
TWD
TZS
UAH
UGX
VND
VUV
WST
XAF
XCD
XOF
XPF
YER
ZAR
ZMK
ZWL
USD
UZS
VEF
Card Entry Type
CardEntryType
An enum representing different card entry types.
Possible values
UNDEFINED
MSR
ICC
CNP
Code example
{
"acquirer": "ACQ_DUMMY",
"mid": "1111",
"tid": "2222",
"mcc": "3333"
}
{
"externalId": "4444"
}
Verification Method
VerificationMethod
An enum representing the possible verification methods used during the transaction.
Possible values:
UNDEFINED
SIGNATURE
PIN
PIN_SIGNATURE
FAILED
NOT_REQUIRED
MOBILE_PASS_CODE
Merchant Auth Credential
Credential
An object to store credentials (Acquirer, Mid, Tid, MCC and ExternalId) for merchant authentication.
Properties
Property | Description |
---|---|
acquirer Acquirer | If present, it links this credential to the specified acquirer. Required if more than one credential is provided. |
mid String | For this transaction, overrides the default MID (merchant ID) saved in the terminal configuration. |
tid String | For this transaction, overrides the default TID (terminal ID) saved in the terminal configuration. |
mcc String | Merchant Category Code, overrides the default MCC saved in the terminal configuration. |
ExternalId String | For this transaction, the External Id will be used to lookup the credential of the merchant in the Handpoint backend and process the transaction accordingly. The External id replaces the need to pass MID/TID/MCC as credentials |
Balance
Balance
Balance available on the card
Properties
Property | Description |
---|---|
amount Integer | The balance |
currency Currency | The balance currency |
positive Boolean | Defines if the balance is positive |
negative Boolean | Defines if the balance is negative |
Code example
"balance": {
"amount": 1000,
"currency": "EUR",
"negative": false,
"positive": true
}
Device Status
DeviceStatus
A class that holds the device status.
Properties
Property | Description |
---|---|
SerialNumber String | The serial number of the device. |
BatteryStatus String | The battery status in percentages of a device. |
BatterymV String | The battery milli volts of a device. |
BatteryCharging String | The battery charging status of a device. |
ExternalPower String | The status of an external power of a device |
ApplicationName String | The application name used on a device |
ApplicationVersion String | The application version number used on a device |
bluetoothName String | The bluetooth interface name used on a device |
statusMessage String | Device human readable status message |
Code example
{
"applicationName": "TestApp",
"applicationVersion": "20.1.0.1",
"batteryCharging": "Charging",
"batteryStatus": "100",
"batterymV": "4134",
"bluetoothName": "A920",
"externalPower": "USB",
"serialNumber": "0821032397",
"statusMessage": "Card reader time out"
}
Card Scheme Name
CardSchemeName
A string representing different card brands.
Possible values
MasterCard
Visa
Maestro
American Express
Discover
JCB
Diners
UnionPay
Interac
Transaction Type
TransactionType
An enum representing different types of transactions.
Possible values
UNDEFINED
SALE
VOID_SALE
REFUND
VOID_REFUND
CANCEL_SALE
CANCEL_REFUND
TOKENIZE_CARD
CARD_PAN
Payment Scenario
PaymentScenario
An enum representing different types of scenario.
Possible values
UNKNOWN
MAGSTRIPE
MAGSTRIPECONTACTLESS
CHIP
CHIPCONTACTLESS
CHIPFAILMAGSTRIPE
Status Info
StatusInfo
A class containing information about the status of the transaction.
Properties
Property | Description |
---|---|
cancelAllowed boolean | A boolean letting the integrator know if the terminal will accept a stop transaction request.) |
status Status | A Status enum representing the status of the transaction. |
message String | A String containing the status message of the transaction. |
deviceStatus DeviceStatus | A DeviceStatus object containing information about the payment terminal. |
Status
status
An enum containing information about the status of a transaction.
Possible values
Undefined
Success
InvalidData
ProcessingError
CommandNotAllowed
NotInitialised
ConnectTimeout
ConnectError
SendingError
ReceivingError
NoDataAvailable
TransactionNotAllowed
UnsupportedCurrency
NoHostAvailable
CardReaderError
CardReadingFailed
InvalidCard
InputTimeout
UserCancelled
InvalidSignature
WaitingForCard
CardInserted
ApplicationSelection
ApplicationConfirmation
AmountValidation
PinInput
ManualCardInput
WaitingForCardRemoval
TipInput
SharedSecretInvalid
SharedSecretAuth
WaitingSignature
WaitingHostConnect
WaitingHostSend
WaitingHostReceive
WaitingHostDisconnect
PinInputCompleted
PosCancelled
RequestInvalid
CardCancelled
CardBlocked
RequestAuthTimeout
RequestPaymentTimeout
´ResponseAuthTimeout´ ´ResponsePaymentTimeout´ IccCardSwiped RemoveCard ScannerIsNotSupported ScannerEvent BatteryTooLow AccountTypeSelection BtIsNotSupported PaymentCodeSelection PartialApproval AmountDueValidation InvalidUrl WaitingCustomerReceipt PrintingMerchantReceipt PrintingCustomerReceipt UpdateStarted UpdateFinished UpdateFailed UpdateProgress WaitingHostPostSend WaitingHostPostReceive Rebooting PrinterOutOfPaper ErrorConnectingToPrinter CardTapped ReceiptPrintSuccess InvalidPinLength OfflinePinAttempt OfflinePinLastAttempt ProcessingSignature CardRemoved TipEntered CardLanguagePreference AutomaticPrintingStarted CancelOperationNotAllowed UpdateSoftwareStarted UpdateSoftwareFinished UpdateSoftwareFailed UpdateSoftwareProgress InstallSoftwareStarted InstallSoftwareFinished InstallSoftwareFailed InstallSoftwareProgress UpdateConfigStarted UpdateConfigFinished UpdateConfigFailed UpdateConfigProgress InitialisationComplete
Tip Configuration
TipConfiguration
Properties
Property | Description |
---|---|
baseAmount String | Base amount used to calculate the tip - in the minor unit of currency (f.ex. 1000 is 10.00 GBP). If no base amount is defined, the transaction amount is used as base amount. |
headerName String | Name of the tipping menu appearing on the terminal. Default: Tip |
tipPercentages Required List | List of percentages used to calculate the tip amount. |
enterAmountEnabled boolean | Flag used to enable the cardholder to manually enter the tip amount. Default: true |
skipEnabled Boolean | Flag used to enable the cardholder to skip the tipping step. Default: true |
footer String | Footer note which will appear on the tipping menu. Default: Empty string |
Code example
{
"tipConfiguration":{
"baseAmount":"2000",
"headerName":"",
"tipPercentages":[
5,
10,
15,
20,
25
],
"enterAmountEnabled":true,
"skipEnabled":false,
"footer":"Thank you!!! ;)"
}
}
Tender Type
TenderType
An enum representing different tender types.
Possible values
NOT_SET
CREDIT
DEBIT